What is encoding-down?
The encoding-down npm package is a codec layer for levelup that provides encoding and decoding of keys and values. It allows you to use different encodings for keys and values, making it easier to work with various data types in a LevelDB store.
What are encoding-down's main functionalities?
Basic Usage
This code demonstrates how to set up a LevelDB store with JSON encoding for values using encoding-down. It shows how to put and get a JSON object.
const levelup = require('levelup');
const leveldown = require('leveldown');
const encode = require('encoding-down');
const db = levelup(encode(leveldown('./mydb'), { valueEncoding: 'json' }));
db.put('key', { some: 'value' }, function (err) {
if (err) return console.log('Ooops!', err);
db.get('key', function (err, value) {
if (err) return console.log('Ooops!', err);
console.log('Got value:', value);
});
});
Custom Encoding
This code demonstrates how to use a custom encoding for values in a LevelDB store. The custom encoding converts values to and from Buffers.
const levelup = require('levelup');
const leveldown = require('leveldown');
const encode = require('encoding-down');
const customEncoding = {
encode: (val) => Buffer.from(val.toString()),
decode: (val) => val.toString(),
buffer: true,
type: 'custom'
};
const db = levelup(encode(leveldown('./mydb'), { valueEncoding: customEncoding }));
db.put('key', 'custom value', function (err) {
if (err) return console.log('Ooops!', err);
db.get('key', function (err, value) {
if (err) return console.log('Ooops!', err);
console.log('Got value:', value);
});
});
Binary Encoding
This code demonstrates how to use binary encoding for values in a LevelDB store. It shows how to put and get a binary value.
const levelup = require('levelup');
const leveldown = require('leveldown');
const encode = require('encoding-down');
const db = levelup(encode(leveldown('./mydb'), { valueEncoding: 'binary' }));
db.put('key', Buffer.from('binary value'), function (err) {
if (err) return console.log('Ooops!', err);
db.get('key', function (err, value) {
if (err) return console.log('Ooops!', err);
console.log('Got value:', value.toString());
});
});
Other packages similar to encoding-down
level-codec
The level-codec package provides encoding and decoding functionality for LevelDB. It allows you to define custom encodings for keys and values, similar to encoding-down. However, encoding-down is more integrated with the level ecosystem and provides a more streamlined API for setting up encodings.
level-transcoder
The level-transcoder package offers a way to transform data as it is read from or written to a LevelDB store. It supports various encoding and decoding schemes, similar to encoding-down. However, encoding-down is more focused on providing a codec layer specifically for levelup, making it easier to use in that context.
encoding-down
An abstract-leveldown
implementation that wraps another store to encode keys and values.
Introduction
Stores like leveldown
can only store strings and Buffers. Other types, though accepted, are serialized before storage, which is an irreversible type conversion. For a richer set of data types you can wrap such a store with encoding-down
. It allows you to specify an encoding to use for keys and values independently. This not only widens the range of input types, but also limits the range of output types. The encoding is applied to all read and write operations: it encodes writes and decodes reads.
Many encodings are builtin courtesy of level-codec
. The default encoding is utf8
which ensures you'll always get back a string. You can also provide a custom encoding like bytewise
- or your own!
Usage
Without any options, encoding-down
defaults to the utf8
encoding.
var levelup = require('levelup')
var leveldown = require('leveldown')
var encode = require('encoding-down')
var db = levelup(encode(leveldown('./db1')))
db.put('example', Buffer.from('encoding-down'), function (err) {
db.get('example', function (err, value) {
console.log(typeof value, value)
})
})
Can we store objects? Yes!
var db = levelup(encode(leveldown('./db2'), { valueEncoding: 'json' }))
db.put('example', { awesome: true }, function (err) {
db.get('example', function (err, value) {
console.log(value)
console.log(typeof value)
})
})
How about storing Buffers, but getting back a hex-encoded string?
var db = levelup(encode(leveldown('./db3'), { valueEncoding: 'hex' }))
db.put('example', Buffer.from([0, 255]), function (err) {
db.get('example', function (err, value) {
console.log(typeof value, value)
})
})
What if we previously stored binary data?
var db = levelup(encode(leveldown('./db4'), { valueEncoding: 'binary' }))
db.put('example', Buffer.from([0, 255]), function (err) {
db.get('example', function (err, value) {
console.log(typeof value, value)
})
db.get('example', { valueEncoding: 'base64' }, function (err, value) {
console.log(typeof value, value)
})
})
And what about keys?
var db = levelup(encode(leveldown('./db5'), { keyEncoding: 'json' }))
db.put({ awesome: true }, 'example', function (err) {
db.get({ awesome: true }, function (err, value) {
console.log(value)
})
})
var db = levelup(encode(leveldown('./db6'), { keyEncoding: 'binary' }))
db.put(Buffer.from([0, 255]), 'example', function (err) {
db.get('00ff', { keyEncoding: 'hex' }, function (err, value) {
console.log(value)
})
})
Usage with level
The level
module conveniently bundles encoding-down
and passes its options
to encoding-down
. This means you can simply do:
var level = require('level')
var db = level('./db7', { valueEncoding: 'json' })
db.put('example', 42, function (err) {
db.get('example', function (err, value) {
console.log(value)
console.log(typeof value)
})
})
API
db = require('encoding-down')(db[, options])
db
must be an abstract-leveldown
compliant storeoptions
are passed to level-codec
:
keyEncoding
: encoding to use for keysvalueEncoding
: encoding to use for values
Both encodings default to 'utf8'
. They can be a string (builtin level-codec
encoding) or an object (custom encoding).
Custom encodings
Please refer to level-codec
documentation for a precise description of the format. Here's a quick example with level
and async/await
just for fun:
var level = require('level')
var lexint = require('lexicographic-integer')
async function main () {
var db = level('./db8', {
keyEncoding: {
type: 'lexicographic-integer',
encode: (n) => lexint.pack(n, 'hex'),
decode: lexint.unpack,
buffer: false
}
})
await db.put(2, 'example')
await db.put(10, 'example')
db.createKeyStream().on('data', console.log)
}
main()
With an npm-installed encoding (modularity ftw!) we can reduce the above to:
var level = require('level')
var lexint = require('lexicographic-integer-encoding')('hex')
var db = level('./db8', {
keyEncoding: lexint
})
Contributing
Level/encoding-down
is an OPEN Open Source Project. This means that:
Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.
See the Contribution Guide for more details.
Donate
To sustain Level
and its activities, become a backer or sponsor on Open Collective. Your logo or avatar will be displayed on our 28+ GitHub repositories and npm packages. 💖
Backers
License
MIT © 2012-present Contributors.